'\" te
.\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
.\" Portions Copyright (C) 1997, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LDAPFILTER.CONF 5 "Jul 9, 2003"
.SH NAME
ldapfilter.conf \- configuration file for LDAP filtering routines
.SH SYNOPSIS
.LP
.nf
\fB/etc/opt/SUNWconn/ldap/current/ldapfilter.conf\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBldapfilter.conf\fR file contains information used by the LDAP filtering
routines.
.sp
.LP
Blank lines and lines that begin with a hash character (\fB#\fR) are treated as
comments and ignored. The configuration information consists of lines that
contain one to five tokens. Tokens are separated by white space, and double
quotes can be used to include white space inside a token.
.sp
.LP
The file consists of a sequence of one or more filter sets. A filter set begins
with a line containing a single token called a \fItag\fR.
.sp
.LP
The filter set consists of a sequence of one or more filter lists. The first
line in a filter list must contain four or five tokens: the \fIvalue
pattern\fR, the \fIdelimiter list\fR, a \fIfiltertemplate\fR, a \fImatch
description\fR, and an optional \fIsearch scope\fR. The \fIvalue pattern\fR is
a regular expression that is matched against the value passed to the LDAP
library call to select the filter list.
.sp
.LP
The \fIdelimiter list\fR is a list of the characters (in the form of a single
string) that can be used to break the \fBvalue\fR into distinct words.
.sp
.LP
The \fIfilter template\fR is used to construct an LDAP filter (see description
below)
.sp
.LP
The \fImatch description\fR is returned to the caller along with a filter as a
piece of text that can be used to describe the sort of LDAP search that took
place. It should correctly compete both of the following phrases: "One \fImatch
description\fR match was found for ..." and "Three \fImatch description\fR
matches were found for...."
.sp
.LP
The \fIsearch scope\fR is optional, and should be one of \fBbase\fR,
\fBonelevel\fR, or \fBsubtree\fR. If \fIsearch scope\fR is not provided, the
default is \fBsubtree\fR.
.sp
.LP
The remaining lines of the filter list should contain two or three tokens, a
\fIfilter template,\fR a \fImatch description\fR and an optional \fIsearch
scope\fR.
.sp
.LP
The \fIfilter template\fR is similar in concept to a \fBprintf\fR(3C) style
format string. Everything is taken literally except for the character
sequences:
.sp
.ne 2
.na
\fB\fB%v\fR \fR
.ad
.RS 9n
Substitute the entire \fBvalue\fR string in place of the \fB%v\fR.
.RE

.sp
.ne 2
.na
\fB\fB%v$\fR \fR
.ad
.RS 9n
Substitute the last word in this field.
.RE

.sp
.ne 2
.na
\fB\fB%v\fR\fIN\fR\fR
.ad
.RS 9n
Substitute word \fIN\fR in this field (where \fIN\fR is a single digit
\fB1\fR-\fB9\fR). Words are numbered from left to right within the value
starting at \fB1\fR.
.RE

.sp
.ne 2
.na
\fB\fB%v\fR\fIM-N\fR\fR
.ad
.RS 9n
Substitute the indicated sequence of words where \fIM\fR and \fIN\fR are both
single digits \fB1\fR-\fB9\fR.
.RE

.sp
.ne 2
.na
\fB\fB%v\fR\fIN-\fR\fR
.ad
.RS 9n
Substitute word \fIN\fR through the last word in \fBvalue\fR where \fIN\fR is
again a single digit \fB1\fR-\fB9\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRAn LDAP Filter Configuration File
.sp
.LP
The following LDAP filter configuration file contains two filter sets,
\fBexample1\fR and \fBexample2 onelevel\fR, each of which contains four filter
lists.

.sp
.in +2
.nf
# ldap filter file
#
example1
"="                " "     "%v"                    "arbitrary filter"
"[0-9][0-9-]*"    " "     "(telephoneNumber=*%v)" "phone number"

"@"                " "     "(mail=%v)"             "email address"

"^.[. _].*"        ". _"   "(cn=%v1* %v2-)"        "first initial"

".*[. _].$"        ". _"   "(cn=%v1-*)"            "last initial"

"[. _]"            ". _"   "(|(sn=%v1-)(cn=%v1-))"        "exact"
                           "(|(sn~=%v1-)(cn~=%v1-))"      "approximate"

".*"               ". "    "(|(cn=%v1)(sn=%v1)(uid=%v1))" "exact"
                           "(|(cn~=%v1)(sn~=%v1))"        "approximate"

"example2 onelevel"
"^..$"  " "   "(|(o=%v)(c=%v)(l=%v)(co=%v))"       "exact" "onelevel"
              "(|(o~=%v)(c~=%v)(l~=%v)(co~=%v))"   "approximate"
"onelevel"

" "     " "   "(|(o=%v)(l=%v)(co=%v)"       "exact"        "onelevel"
              "(|(o~=%v)(l~=%v)(co~=%v)"    "approximate"  "onelevel"

"."    " "   "(associatedDomain=%v)"       "exact"        "onelevel"

".*"    " "   "(|(o=%v)(l=%v)(co=%v)"       "exact"        "onelevel"
              "(|(o~=%v)(l~=%v)(co~=%v)"    "approximate"  "onelevel"
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for a description of the following attributes:
.sp

.sp
.TS
box;
l | l
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
Stability Level	Evolving
.TE

.SH SEE ALSO
.sp
.LP
.BR ldap_getfilter (3LDAP),
.BR ldap_ufn (3LDAP),
.BR attributes (7)
